sgdk: sound.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Defines | Functions
sound.h File Reference

Audio / Sound stuff. More...

Go to the source code of this file.

## Defines

#define | SOUND_PCM_CH_AUTO 0x00
#define | SOUND_PCM_CH1 Z80_DRV_CH0_SFT
#define | SOUND_PCM_CH2 Z80_DRV_CH1_SFT
#define | SOUND_PCM_CH3 Z80_DRV_CH2_SFT
#define | SOUND_PCM_CH4 Z80_DRV_CH3_SFT
#define | SOUND_PCM_CH1_MSK Z80_DRV_CH0
#define | SOUND_PCM_CH2_MSK Z80_DRV_CH1
#define | SOUND_PCM_CH3_MSK Z80_DRV_CH2
#define | SOUND_PCM_CH4_MSK Z80_DRV_CH3
#define | SOUND_RATE_32000 0
#define | SOUND_RATE_22050 1
#define | SOUND_RATE_16000 2
#define | SOUND_RATE_13400 3
#define | SOUND_RATE_11025 4
#define | SOUND_RATE_8000 5
#define | SOUND_PAN_LEFT 0x80
#define | SOUND_PAN_RIGHT 0x40
#define | SOUND_PAN_CENTER 0xC0

## Functions

u8 | SND_isPlaying_PCM ()
| Return play status (Single channel PCM player driver).
void | SND_startPlay_PCM (const u8 *sample, const u32 len, const u8 rate, const u8 pan, const u8 loop)
| Start playing a sample (Single channel PCM player driver). If a sample was currently playing then it's stopped and the new sample is played instead.
void | SND_stopPlay_PCM ()
| Stop playing (Single channel PCM player driver). No effect if no sample was currently playing.
u8 | SND_isPlaying_2ADPCM (const u16 channel_mask)
| Return play status of specified channel (2 channels ADPCM player driver).
void | SND_startPlay_2ADPCM (const u8 *sample, const u32 len, const u16 channel, const u8 loop)
| Start playing a sample on specified channel (2 channels ADPCM player driver). If a sample was currently playing on this channel then it's stopped and the new sample is played instead.
void | SND_stopPlay_2ADPCM (const u16 channel)
| Stop playing the specified channel (2 channels ADPCM player driver). No effect if no sample was currently playing on this channel.
u8 | SND_isPlaying_4PCM_ENV (const u16 channel_mask)
| Return play status of specified channel (4 channels PCM ENV player driver).
void | SND_startPlay_4PCM_ENV (const u8 *sample, const u32 len, const u16 channel, const u8 loop)
| Start playing a sample on specified channel (4 channels PCM ENV player driver). If a sample was currently playing on this channel then it's stopped and the new sample is played instead.
void | SND_stopPlay_4PCM_ENV (const u16 channel)
| Stop playing the specified channel (4 channels PCM ENV player driver). No effect if no sample was currently playing on this channel.
void | SND_setVolume_4PCM_ENV (const u16 channel, const u8 volume)
| Change envelop / volume of specified channel (4 channels PCM ENV player driver).
u8 | SND_getVolume_4PCM_ENV (const u16 channel)
| Return envelop / volume level of specified channel (4 channels PCM ENV player driver).
u8 | SND_isPlaying_MVS ()
| Return play status for FM (MVS music player driver).
void | SND_startPlay_MVS (const u8 *music, const u8 loop)
| Start playing the specified FM track (MVS music player driver).
void | SND_stopPlay_MVS ()
| Stop playing FM music (MVS music player driver).
void | SND_setTempo_MVS (u8 tempo)
| Set the FM music tempo (MVS music player driver).
void | SND_startDAC_MVS (const u8 *sample, u16 size)
| Start playing the specified DAC sample (MVS music player driver).
void | SND_stopDAC_MVS ()
| Stop playing DAC sample (MVS music player driver).
u8 | SND_isPlayingPSG_MVS ()
| Return play status for PSG (MVS music player driver).
void | SND_startPSG_MVS (const u8 *music)
| Start playing the specified PSG music (MVS music player driver).
void | SND_stopPSG_MVS ()
| Stop playing PSG music.
void | SND_enablePSG_MVS (u8 chan)
| Enable the specified PSG channel.
void | SND_disablePSG_MVS (u8 chan)
| Disable the specified PSG channel.
void | SND_startPlay_TFM (const u8 *song)
| Start playing the specified TFM track (TFM music player driver).
void | SND_stopPlay_TFM ()
| Stop playing music (TFM music player driver).
u8 | SND_isPlaying_VGM ()
| Return play state of VGM driver.
void | SND_startPlay_VGM (const u8 *song)
| Start playing the specified VGM track (VGM music player driver).
void | SND_stopPlay_VGM ()
| Stop playing music (VGM music player driver).
void | SND_resumePlay_VGM ()
| Resume playing music after stopping with SND_stopPlay_VGM.
void | SND_playSfx_VGM (const u8 *sfx, u16 len)
| Play a PCM sound effect while a VGM track is playing.
u8 | SND_isPlaying_XGM ()
| Returns play music state (XGM music player driver).
void | SND_startPlay_XGM (const u8 *song)
| Start playing the specified XGM track (XGM music player driver).
void | SND_stopPlay_XGM ()
| Stop playing music (XGM music player driver).
void | SND_resumePlay_XGM ()
| Resume playing music after stopping with SND_stopPlay_XGM (XGM music player driver).
u8 | SND_isPlayingPCM_XGM (const u16 channel_mask)
| Return play status of specified PCM channel (XGM music player driver).
void | SND_setPCM_XGM (const u8 id, const u8 *sample, const u32 len)
| Declare a new PCM sample (maximum = 255) for the XGM music player driver. Sample id < 64 are reserved for music while others are used for SFX so if you want to declare a new SFX PCM sample use an id >= 64.
void | SND_setPCMFast_XGM (const u8 id, const u8 *sample, const u32 len)
| Same as SND_setPCM_XGM but fast version. This method assume that XGM driver is loaded and that 68000 has access to Z80 bus.
void | SND_startPlayPCM_XGM (const u8 id, const u8 priority, const u16 channel)
| Play a PCM sample on specified channel (XGM music player driver). If a sample was currently playing on this channel then priority of the newer sample should be are compared tthen it's stopped and the new sample is played instead.
void | SND_stopPlayPCM_XGM (const u16 channel)
| Stop play PCM on specified channel (XGM music player driver). No effect if no sample was currently playing on this channel.
u16 | SND_getCPULoad_XGM ()
| Returns an estimation of the Z80 CPU load (XGM driver). It returns value between ~80% (minimum value) to >100% (if we have some frames late). WARNING: You should call this method at each frame to get meaningful value !

## Detailed Description

Audio / Sound stuff.

Author:
  Stephane Dallongeville

Date:
  08/2011

This unit provides advanced sound playback methods through differents Z80 drivers.
Z80_DRIVER_PCM
Single channel 8 bits signed sample driver.
It can play a sample (8 bit signed) from 8 Khz up to 32 Khz rate.
Z80_DRIVER_2ADPCM
2 channels 4 bits ADPCM sample driver.
It can mix up to 2 ADCPM samples at a fixed 22050 Hz Khz rate.
Address and size of samples have to be 256 bytes boundary.
Z80_DRIVER_4PCM_ENV
4 channels 8 bits signed sample driver with volume support.
It can mix up to 4 samples (8 bit signed) at a fixed 16 Khz rate.
with volume support (16 levels du to memory limitation).
Address and size of samples have to be 256 bytes boundary.
The driver does support "cutoff" when mixing so you can use true 8 bits samples :)
Z80_DRIVER_MVS
MVS music player driver.
Z80_DRIVER_TFM
TFM music player driver.
Z80_DRIVER_VGM
VGM music player driver.
It supports 1 PCM channel at a fixed 8 Khz and allows to play SFX through the named PCM channel.
Written by Sigflup and kubilus1.
Z80_DRIVER_XGM
eXtended VGM music player driver.
This driver takes VGM (or XGM) file as input to play music.
It supports 4 PCM channels at a fixed 14 Khz and allows to play SFX through PCM with 16 level of priority.
The driver is designed to avoid DMA contention when possible (depending CPU load).

## Define Documentation

#define SOUND_PAN_CENTER 0xC0

Center (laft and right) speaker panning.

#define SOUND_PAN_LEFT 0x80

Left speaker panning.

#define SOUND_PAN_RIGHT 0x40

Right speaker panning.

#define SOUND_PCM_CH1 Z80_DRV_CH0_SFT

PCM channel 1.

#define SOUND_PCM_CH1_MSK Z80_DRV_CH0

PCM channel 1 selection mask.

#define SOUND_PCM_CH2 Z80_DRV_CH1_SFT

PCM channel 2.

#define SOUND_PCM_CH2_MSK Z80_DRV_CH1

PCM channel 2 selection mask.

#define SOUND_PCM_CH3 Z80_DRV_CH2_SFT

PCM channel 3.

#define SOUND_PCM_CH3_MSK Z80_DRV_CH2

PCM channel 3 selection mask.

#define SOUND_PCM_CH4 Z80_DRV_CH3_SFT

PCM channel 4.

#define SOUND_PCM_CH4_MSK Z80_DRV_CH3

PCM channel 4 selection mask.

#define SOUND_PCM_CH_AUTO 0x00

Auto select PCM channel to use.

#define SOUND_RATE_11025 4

PCM sample rate set to 11025 Hz.

#define SOUND_RATE_13400 3

PCM sample rate set to 13400 Hz.
Good compromise for rom space and quality.

#define SOUND_RATE_16000 2

PCM sample rate set to 16 Khz.

#define SOUND_RATE_22050 1

PCM sample rate set to 22050 Hz.
Best quality but take lot of rom space.

#define SOUND_RATE_32000 0

PCM sample rate set to 32 Khz.
Best quality but take lot of rom space.

#define SOUND_RATE_8000 5

PCM sample rate set to 8 Khz.
Worst quality but take less rom place.

## Function Documentation

void SND_disablePSG_MVS | ( | u8 | chan | ) |

Disable the specified PSG channel.

Parameters:

  chan | PSG channel to disable.

void SND_enablePSG_MVS | ( | u8 | chan | ) |

Enable the specified PSG channel.

Parameters:

  chan | PSG channel to enable.

u8 SND_getVolume_4PCM_ENV | ( | const u16 | channel | ) |

Return envelop / volume level of specified channel (4 channels PCM ENV player driver).

Parameters:

  channel

  Channel we want to retrieve envelop level.
  SOUND_PCM_CH1 = channel 1
  SOUND_PCM_CH2 = channel 2
  SOUND_PCM_CH3 = channel 3
  SOUND_PCM_CH4 = channel 4

Returns:
  Envelop of specified channel.
  The returned value is comprised between 0 (quiet) to 15 (loud).

u8 SND_isPlaying_2ADPCM | ( | const u16 | channel_mask | ) |

Return play status of specified channel (2 channels ADPCM player driver).

Parameters:

  channel_mask

  Channel(s) we want to retrieve play state.
  SOUND_PCM_CH1_MSK = channel 1
  SOUND_PCM_CH2_MSK = channel 2
  You can combine mask to retrieve state of severals channels at once:
  `isPlaying_2ADPCM(SOUND_PCM_CH1_MSK | SOUND_PCM_CH2_MSK)`
  will actually return play state for channel 1 and channel 2.

Returns:
  Return non zero if specified channel(s) is(are) playing.

u8 SND_isPlaying_4PCM_ENV | ( | const u16 | channel_mask | ) |

Return play status of specified channel (4 channels PCM ENV player driver).

Parameters:

  channel_mask

  Channel(s) we want to retrieve play state.
  SOUND_PCM_CH1_MSK = channel 1
  SOUND_PCM_CH2_MSK = channel 2
  SOUND_PCM_CH3_MSK = channel 3
  SOUND_PCM_CH4_MSK = channel 4
  You can combine mask to retrieve state of severals channels at once:
  `isPlaying_2ADPCM(SOUND_PCM_CH1_MSK | SOUND_PCM_CH2_MSK)`
  will actually return play state for channel 1 and channel 2.

Returns:
  Return non zero if specified channel(s) is(are) playing.

u8 SND_isPlaying_MVS | ( |  | ) |

Return play status for FM (MVS music player driver).

Returns:
  Return non zero if FM is currently playing.

u8 SND_isPlaying_PCM | ( |  | ) |

Return play status (Single channel PCM player driver).

Returns:
  Return non zero if PCM player is currently playing a sample

u8 SND_isPlayingPCM_XGM | ( | const u16 | channel_mask | ) |

Return play status of specified PCM channel (XGM music player driver).

Parameters:

  channel_mask

  Channel(s) we want to retrieve play state.
  SOUND_PCM_CH1_MSK = channel 1
  SOUND_PCM_CH2_MSK = channel 2
  SOUND_PCM_CH3_MSK = channel 3
  SOUND_PCM_CH4_MSK = channel 4
  You can combine mask to retrieve state of severals channels at once:
  `isPlayingPCM_XGM(SOUND_PCM_CH1_MSK | SOUND_PCM_CH2_MSK)`
  will actually return play state for channel 1 and channel 2.

Returns:
  Return non zero if specified channel(s) is(are) playing.

u8 SND_isPlayingPSG_MVS | ( |  | ) |

Return play status for PSG (MVS music player driver).

Returns:
  Return non zero if PSG is currently playing.

void SND_setPCM_XGM | ( | const u8 | id,
|  | const u8 * | sample,
|  | const u32 | len
| ) |  |

Declare a new PCM sample (maximum = 255) for the XGM music player driver.
Sample id < 64 are reserved for music while others are used for SFX so if you want to declare a new SFX PCM sample use an id >= 64.

Parameters:

  id | Sample id: value 0 is not allowed values from 1 to 63 are used for music values from 64 to 255 are used for SFX
  sample | Sample address, should be 256 bytes boundary aligned SGDK automatically align sample resource as needed
  len | Size of sample in bytes, should be a multiple of 256 SGDK automatically adjust resource size as needed

void SND_setPCMFast_XGM | ( | const u8 | id,
|  | const u8 * | sample,
|  | const u32 | len
| ) |  |

Same as SND_setPCM_XGM but fast version.
This method assume that XGM driver is loaded and that 68000 has access to Z80 bus.

Parameters:

  id | Sample id: value 0 is not allowed values from 1 to 63 are used for music values from 64 to 255 are used for SFX
  sample | Sample address, should be 256 bytes boundary aligned SGDK automatically align sample resource as needed
  len | Size of sample in bytes, should be a multiple of 256 SGDK automatically adjust resource size as needed

void SND_setVolume_4PCM_ENV | ( | const u16 | channel,
|  | const u8 | volume
| ) |  |

Change envelop / volume of specified channel (4 channels PCM ENV player driver).

Parameters:

  channel

  Channel we want to set envelop.
  SOUND_PCM_CH1 = channel 1
  SOUND_PCM_CH2 = channel 2
  SOUND_PCM_CH3 = channel 3
  SOUND_PCM_CH4 = channel 4

  volume | Volume to set : 16 possible level from 0 (minimum) to 15 (maximum).

void SND_startDAC_MVS | ( | const u8 * | sample,
|  | u16 | size
| ) |  |

Start playing the specified DAC sample (MVS music player driver).

Parameters:

  sample | DAC sample address.
  size | Sample size. Maximum sample size is 65536 byte.

void SND_startPlay_2ADPCM | ( | const u8 * | sample,
|  | const u32 | len,
|  | const u16 | channel,
|  | const u8 | loop
| ) |  |

Start playing a sample on specified channel (2 channels ADPCM player driver).
If a sample was currently playing on this channel then it's stopped and the new sample is played instead.

Parameters:

  sample | Sample address, should be 128 bytes boundary aligned SGDK automatically align resource as needed
  len | Size of sample in bytes, should be a multiple of 128 SGDK automatically adjust resource size as needed
  channel | Channel where we want to play sample. SOUND_PCM_CH1 = channel 1 SOUND_PCM_CH2 = channel 2
  loop | Loop flag. If non zero then the sample will be played in loop (else sample is played only once).

void SND_startPlay_4PCM_ENV | ( | const u8 * | sample,
|  | const u32 | len,
|  | const u16 | channel,
|  | const u8 | loop
| ) |  |

Start playing a sample on specified channel (4 channels PCM ENV player driver).
If a sample was currently playing on this channel then it's stopped and the new sample is played instead.

Parameters:

  sample | Sample address, should be 256 bytes boundary aligned SGDK automatically align resource as needed
  len | Size of sample in bytes, should be a multiple of 256 SGDK automatically adjust resource size as needed

  channel

  Channel where we want to play sample.
  SOUND_PCM_CH1 = channel 1
  SOUND_PCM_CH2 = channel 2
  SOUND_PCM_CH3 = channel 3
  SOUND_PCM_CH4 = channel 4

  loop | Loop flag. If non zero then the sample will be played in loop (else sample is played only once).

void SND_startPlay_MVS | ( | const u8 * | music,
|  | const u8 | loop
| ) |  |

Start playing the specified FM track (MVS music player driver).

Parameters:

  music | FM track address.
  loop | Loop flag. If non zero then the sample will be played in loop (else sample is played only once).

void SND_startPlay_PCM | ( | const u8 * | sample,
|  | const u32 | len,
|  | const u8 | rate,
|  | const u8 | pan,
|  | const u8 | loop
| ) |  |

Start playing a sample (Single channel PCM player driver).
If a sample was currently playing then it's stopped and the new sample is played instead.

Parameters:

  sample | Sample address, should be 256 bytes boundary aligned SGDK automatically align resource as needed
  len | Size of sample in bytes, should be a multiple of 256 SGDK automatically adjust resource size as needed

  rate

  Playback rate :
  SOUND_RATE_32000 = 32 Khz (best quality but take lot of rom space)
  SOUND_RATE_22050 = 22 Khz
  SOUND_RATE_16000 = 16 Khz
  SOUND_RATE_13400 = 13.4 Khz
  SOUND_RATE_11025 = 11 Khz
  SOUND_RATE_8000 = 8 Khz (worst quality but take less rom place)

  pan | Panning : SOUND_PAN_LEFT = play on left speaker SOUND_PAN_RIGHT = play on right speaker SOUND_PAN_CENTER = play on both speaker
  loop | Loop flag. If non zero then the sample will be played in loop (else sample is played only once).

void SND_startPlay_TFM | ( | const u8 * | song | ) |

Start playing the specified TFM track (TFM music player driver).

Parameters:

  song | TFM track address.

void SND_startPlay_VGM | ( | const u8 * | song | ) |

Start playing the specified VGM track (VGM music player driver).

Parameters:

  song | VGM track address.

void SND_startPlay_XGM | ( | const u8 * | song | ) |

Start playing the specified XGM track (XGM music player driver).

Parameters:

  song | XGM track address.

void SND_startPlayPCM_XGM | ( | const u8 | id,
|  | const u8 | priority,
|  | const u16 | channel
| ) |  |

Play a PCM sample on specified channel (XGM music player driver).
If a sample was currently playing on this channel then priority of the newer sample should be are compared tthen it's stopped and the new sample is played instead.

Parameters:

  id | Sample id (set #SND_setSample_XGM method)
  priority | Value should go from 0 to 15 where 0 is lowest priority and 15 the highest one. If the channel was already playing the priority is used to determine if the new SFX should replace the current one (new priority >= old priority).

  channel

  Channel where we want to play sample.
  SOUND_PCM_CH1 = channel 1
  SOUND_PCM_CH2 = channel 2
  SOUND_PCM_CH3 = channel 3
  SOUND_PCM_CH4 = channel 4

void SND_startPSG_MVS | ( | const u8 * | music | ) |

Start playing the specified PSG music (MVS music player driver).

Parameters:

  music | PSG music address.

void SND_stopPlay_2ADPCM | ( | const u16 | channel | ) |

Stop playing the specified channel (2 channels ADPCM player driver).
No effect if no sample was currently playing on this channel.

Parameters:

  channel | Channel we want to stop. SOUND_PCM_CH1 = channel 1 SOUND_PCM_CH2 = channel 2

void SND_stopPlay_4PCM_ENV | ( | const u16 | channel | ) |

Stop playing the specified channel (4 channels PCM ENV player driver).
No effect if no sample was currently playing on this channel.

Parameters:

  channel

  Channel we want to stop.
  SOUND_PCM_CH1 = channel 1
  SOUND_PCM_CH2 = channel 2
  SOUND_PCM_CH3 = channel 3
  SOUND_PCM_CH4 = channel 4

void SND_stopPlayPCM_XGM | ( | const u16 | channel | ) |

Stop play PCM on specified channel (XGM music player driver).
No effect if no sample was currently playing on this channel.

Parameters:

  channel

  Channel we want to stop.
  SOUND_PCM_CH1 = channel 1
  SOUND_PCM_CH2 = channel 2
  SOUND_PCM_CH3 = channel 3
  SOUND_PCM_CH4 = channel 4

All Classes Files Functions Variables Typedefs Enumerations Defines